package simpledb.optimizer;

import simpledb.execution.Predicate;

/**
 * Histogram<T> 接口表示一个通用的统计直方图，用于估计数据库查询中谓词的选择率（selectivity）。
 *
 * 直方图记录数据分布情况，用于优化器估算某个条件会筛选出多少数据，从而帮助选择最优的查询执行计划。
 *
 * @param <T> 数据类型，例如 Integer、String 等，表示字段值的类型
 */
public interface Histogram<T> {

    /**
     * 将一个值添加到直方图中。
     * 通过多次调用该方法，可以构建整个字段的数据分布。
     *
     * @param v 要添加到直方图中的值
     */
    void addValue(final T v);

    /**
     * 根据当前直方图估计给定谓词和值的选择率。
     *
     * 例如：如果 op 是 "GREATER_THAN"，v 是 5，
     * 则返回大于 5 的数据所占的比例（0.0 ~ 1.0）。
     *
     * @param op 操作符，如 EQUALS, GREATER_THAN 等
     * @param v 值，作为比较的标准
     * @return 返回满足该谓词的元组在总数据中的估计比例（0.0 到 1.0）
     */
    double estimateSelectivity(Predicate.Op op, T v);

    /**
     * 获取该直方图的平均选择率。
     *
     * 这个方法不是实现基本连接优化所必需的，
     * 但在实现更高效的优化策略时可能会用到。
     *
     * @return 平均选择率
     */
    double avgSelectivity();
}
